home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.073 < prev    next >
Encoding:
Text File  |  1991-06-28  |  6.2 KB  |  135 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #73:         Using User Tool Sets
  9.  
  10. Revised by:  Dave "Flag Bits" Lyons                                 July 1991
  11. Written by:  Dave Lyons                                         November 1989
  12.  
  13. This Technical Note explains how to write a user tool set and why writing a 
  14. user tool set is better than stealing a system tool set number.
  15.  
  16. Changes since January 1991:  Expanded recommendation on where to keep user 
  17. tool set files on disk and clarified SetTSPtr information.
  18. _____________________________________________________________________________
  19.  
  20.  
  21. The Apple IIgs Toolbox Reference describes system tool sets, which are 
  22. usually called through the system tool dispatcher vectors 1 ($E10000) and 2 
  23. ($E10004).
  24.  
  25. There are 255 possible system tool set numbers (1 through 255).  All of these 
  26. are reserved for definition by the system.  If your program is "borrowing" a 
  27. system tool set number, please feel guilty and switch over to the user tool 
  28. set numbers.  There are 255 of them too, and they're called through user tool 
  29. dispatcher vectors 1 ($E10008) and 2 ($E1000C).  All 255 user tool set 
  30. numbers are available for the current application to use as it chooses.  
  31. (Desk accessories are forbidden to use user tool sets.)
  32.  
  33. Of the four tool dispatcher vectors, only the first one ($E10000) has 
  34. received a lot of publicity.  $E10008  works just like $E10000, except that 
  35. it passes control to a user tool set instead of a system tool set.
  36.  
  37. The second vector of each pair ($E10004 and $E1000C) works just like the 
  38. first, except that one extra RTL address must be pushed onto the stack after 
  39. any parameters are pushed.  This way you can have a subroutine to do some or 
  40. all of your toolbox dispatching, and that subroutine can do extra processing 
  41. before or after the tool call, or both.
  42.  
  43.  
  44. How Can I Write a User Tool Set?
  45.  
  46. Appendix A of Toolbox Reference, Volume 2, shows how to write a user tool 
  47. set.  Your tool set's Work Area Pointer is a four-byte value you can set with 
  48. SetWAP and get with GetWAP.  The WAP value is already loaded into the Y and A 
  49. registers every time one of your tool set's functions gets control.  The 
  50. traditional use for the WAP is to keep track of an area of memory owned by 
  51. your tool set.
  52.  
  53. If you do use the WAP in a conventional way, your xxxStatus function should 
  54. return TRUE if the WAP is nonzero; your xxxStartUp function should set the 
  55. WAP to a non-zero value pointing to some memory space you own (provided by 
  56. the caller, or allocated with NewHandle using a memory ID provided by the 
  57. caller); and your xxxShutDown function should set the WAP back to zero.
  58.  
  59. Since the X register contains the tool set and function number when one of 
  60. your functions gets control, it is not necessary for a tool set to be written 
  61. to be used as a predetermined user tool set number.  At execution time, your 
  62. tool set can compute the proper error codes and values to send to GetWAP and 
  63. SetWAP.
  64.  
  65. Note:    At the bottom of page A-8 of the Apple IIgs Toolbox Reference, 
  66. Volume 2, "lda #$90" should read "lda #$8100" for version 1.0 prototype.  On 
  67. page A-10, the figure should show two RTL addresses (6 bytes) on the stack.
  68.  
  69.  
  70. ToStrip and ToBusyStrip Vectors
  71.  
  72. These two vectors are for tool sets to jump to when a function exits.
  73.  
  74. ToBusyStrip     $E10180
  75. ToStrip         $E10184
  76.  
  77. Inputs:         X = error code (0 if no error)
  78.                 Y = number of bytes of input parameters to strip
  79.  
  80. When your function is ready to exit, set up the registers and jump to 
  81. ToStrip.  It shifts the six bytes of RTL addresses up by Y bytes, sets up A 
  82. and the carry flag appropriately, and returns to whomever called the tool.
  83.  
  84. If the system busy flag needs to be decremented, jump to ToBusyStrip instead 
  85. of ToStrip.
  86.  
  87.  
  88. How Can I Load My Tool Set From Disk?
  89.  
  90. One way to load your tool set from disk is to use InitialLoad or 
  91. InitialLoad2, supplying a pathname like "9:MyToolset" (prefix 9 is initially 
  92. set to the directory containing your application; prefix 1 also works, but 
  93. its length is limited to 64 characters).  You can then use SetTSPtr to tell 
  94. the Tool Locator about your tool set, as shown in Appendix A.
  95.  
  96. Note that SetTSPtr calls your xxxBootInit function.  Even if there is no 
  97. useful work to be done at BootInit time, you still need to have a BootInit 
  98. function (function number 1) that returns $0000 in the Accumulator and the 
  99. carry flag cleared..
  100.  
  101. When you're done with your tool set, call UserShutdown on the memory ID 
  102. returned by InitialLoad, so the memory it's using is disposed of or made 
  103. purgeable.  (You can shut it down and allow it to remain in memory in a 
  104. purgeable state; if you do this, you should try to revive your tool set with 
  105. Restart before you try InitialLoad or InitialLoad2.)
  106.  
  107. To allow several applications to share one copy of a user tool set file, you 
  108. may want to keep your user tool set in the user's *:System:Tools folder.  To 
  109. avoid duplicate file names, leave the ToolXXX names for System tool sets, and 
  110. give your user tool set a descriptive name.
  111.  
  112. If your tool set is not found in the *:System:Tools folder, you can then 
  113. check the 9: folder.  This way users do not need to burden their 
  114. *:System:Tools folders if few of their applications use a particular user 
  115. tool set or if space on their boot volume is limited.
  116.  
  117. When your application quits and calls TLShutDown, the system disconnects your 
  118. tool set from the user tool set TPT.  If the UserShutDown is not  followed 
  119. immediately by the TLShutDown, you may wish to use SetTSPtr to cleanly remove 
  120. your tool set from the system (set the tool set pointer so that it points at 
  121. a zero word).
  122.  
  123. Note:    Because of the way the tool dispatcher transfers control to toolbox 
  124. functions, a function's entry point must not be at the first byte of a bank 
  125. ($xx0000).  This is normally not an issue, since it's common to put the 
  126. actual code right after the function pointer table, all in one load segment.  
  127. Just make sure no function begins at the first byte of a load segment, and 
  128. you're safe.
  129.  
  130.  
  131. Further Reference
  132. _____________________________________________________________________________
  133.   o   Apple IIgs Toolbox Reference, Volume 2
  134.   o   GS/OS Reference
  135.